home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2000 / MacHack 2000.toast / pc / The Hacks / MacHacksBug / Python 1.5.2c1 / Lib / threading_api.py < prev    next >
Encoding:
Python Source  |  2000-06-23  |  22.2 KB  |  639 lines
  1. """Proposed new higher-level threading interfaces.
  2.  
  3. This module is safe for use with 'from threading import *'.  It
  4. defines the following objects:
  5.  
  6. Lock()
  7.     A factory function that returns a new primitive lock object.  Once
  8.     a thread has acquired it, subsequent attempts to acquire it block,
  9.     until it is released; any thread may release it.
  10.  
  11. RLock()
  12.     A factory function that returns a new reentrant lock object.
  13.     A reentrant lock must be released by the thread that acquired it.
  14.     Once a thread has acquired a reentrant lock, the same thread may
  15.     acquire it again without blocking; the thread must release it once
  16.     for each time it has acquired it.
  17.  
  18. Condition()
  19.     A factory function that returns a new condition variable object.
  20.     A condition variable allows one or more threads to wait until they
  21.     are notified by another thread.
  22.  
  23. Semaphore()
  24.     A factory function that returns a new semaphore object.  A
  25.     semaphore manages a counter representing the number of release()
  26.     calls minus the number of acquire() calls, plus an initial value.
  27.     The acquire() method blocks if necessary until it can return
  28.     without making the counter negative.
  29.  
  30. Event()
  31.     A factory function that returns a new event object.  An event
  32.     manages a flag that can be set to true with the set() method and
  33.     reset to false with the clear() method.  The wait() method blocks
  34.     until the flag is true.
  35.  
  36. Thread
  37.     A class that represents a thread of control -- subclassable.
  38.  
  39. currentThread()
  40.     A function that returns the Thread object for the caller's thread.
  41.  
  42. activeCount()
  43.     A function that returns the number of currently active threads.
  44.  
  45. enumerate()
  46.     A function that returns a list of all currently active threads.
  47.  
  48. Detailed interfaces for each of these are documented below in the form
  49. of pseudo class definitions.  Note that the classes marked as ``do not
  50. subclass'' are actually implemented as factory functions; classes are
  51. shown here as a way to structure the documentation only.
  52.  
  53. The design of this module is loosely based on Java's threading model.
  54. However, where Java makes locks and condition variables basic behavior
  55. of every object, they are separate objects in Python.  Python's Thread
  56. class supports a subset of the behavior of Java's Thread class;
  57. currently, there are no priorities, no thread groups, and threads
  58. cannot be destroyed, stopped, suspended, resumed, or interrupted.  The
  59. static methods of Java's Thread class, when implemented, are mapped to
  60. module-level functions.
  61.  
  62. All methods described below are executed atomically.
  63.  
  64. """
  65.  
  66.  
  67. class Lock:
  68.     """Primitive lock object.
  69.  
  70.     *** DO NOT SUBCLASS THIS CLASS ***
  71.  
  72.     A primitive lock is a synchronization primitive that is not owned
  73.     by a particular thread when locked.  In Python, it is currently
  74.     the lowest level synchronization primitive available, implemented
  75.     directly by the thread extension module.
  76.  
  77.     A primitive lock is in one of two states, ``locked'' or
  78.     ``unlocked''.  It is created in the unlocked state.  It has two
  79.     basic methods, acquire() and release().  When the state is
  80.     unlocked, acquire() changes the state to locked and returns
  81.     immediately.  When the state is locked, acquire() blocks until a
  82.     call to release() in another thread changes it to unlocked, then
  83.     the acquire() call resets it to locked and returns.  The release()
  84.     method should only be called in the locked state; it changes the
  85.     state to unlocked and returns immediately.  When more than one
  86.     thread is blocked in acquire() waiting for the state to turn to
  87.     unlocked, only one thread proceeds when a release() call resets
  88.     the state to unlocked; which one of the waiting threads proceeds
  89.     is not defined, and may vary across implementations.
  90.  
  91.     All methods are executed atomically.
  92.  
  93.     """
  94.  
  95.     def acquire(self, blocking=1):
  96.         """Acquire a lock, blocking or non-blocking.
  97.  
  98.         When invoked without arguments, block until the lock is
  99.         unlocked, then set it to locked, and return.  There is no
  100.         return value in this case.
  101.  
  102.         When invoked with the 'blocking' argument set to true, do the
  103.         same thing as when called without arguments, and return true.
  104.  
  105.         When invoked with the 'blocking' argument set to false, do not
  106.         block.  If a call without argument would block, return false
  107.         immediately; otherwise, do the same thing as when called
  108.         without arguments, and return true.
  109.  
  110.         """
  111.  
  112.     def release(self):
  113.         """Release a lock.
  114.  
  115.         When the lock is locked, reset it to unlocked, and return.  If
  116.         any other threads are blocked waiting for the lock to become
  117.         unlocked, allow exactly one of them to proceed.
  118.  
  119.         Do not call this method when the lock is unlocked.
  120.  
  121.         There is no return value.
  122.  
  123.         """
  124.  
  125.  
  126. class RLock:
  127.     """Reentrant lock object.
  128.  
  129.     *** DO NOT SUBCLASS THIS CLASS ***
  130.  
  131.     A reentrant lock is a synchronization primitive that may be
  132.     acquired multiple times by the same thread.  Internally, it uses
  133.     the concepts of ``owning thread'' and ``recursion level'' in
  134.     addition to the locked/unlocked state used by primitive locks.  In
  135.     the locked state, some thread owns the lock; in the unlocked
  136.     state, no thread owns it.
  137.  
  138.     To lock the lock, a thread calls its acquire() method; this
  139.     returns once the thread owns the lock.  To unlock the lock, a
  140.     thread calls its release() method.  acquire()/release() call pairs
  141.     may be nested; only the final release() (i.e. the release() of the
  142.     outermost pair) resets the lock to unlocked and allows another
  143.     thread blocked in acquire() to proceed.
  144.  
  145.     """
  146.  
  147.     def acquire(self, blocking=1):
  148.         """Acquire a lock, blocking or non-blocking.
  149.  
  150.         When invoked without arguments: if this thread already owns
  151.         the lock, increment the recursion level by one, and return
  152.         immediately.  Otherwise, if another thread owns the lock,
  153.         block until the lock is unlocked.  Once the lock is unlocked
  154.         (not owned by any thread), then grab ownership, set the
  155.         recursion level to one, and return.  If more than one thread
  156.         is blocked waiting until the lock is unlocked, only one at a
  157.         time will be able to grab ownership of the lock.  There is no
  158.         return value in this case.
  159.  
  160.         When invoked with the 'blocking' argument set to true, do the
  161.         same thing as when called without arguments, and return true.
  162.  
  163.         When invoked with the 'blocking' argument set to false, do not
  164.         block.  If a call without argument would block, return false
  165.         immediately; otherwise, do the same thing as when called
  166.         without arguments, and return true.
  167.  
  168.         """
  169.  
  170.     def release(self):
  171.         """Release a lock.
  172.  
  173.         Only call this method when the calling thread owns the lock.
  174.         Decrement the recursion level.  If after the decrement it is
  175.         zero, reset the lock to unlocked (not owned by any thread),
  176.         and if any other threads are blocked waiting for the lock to
  177.         become unlocked, allow exactly one of them to proceed.  If
  178.         after the decrement the recursion level is still nonzero, the
  179.         lock remains locked and owned by the calling thread.
  180.  
  181.         Do not call this method when the lock is unlocked.
  182.  
  183.         There is no return value.
  184.  
  185.         """
  186.  
  187.  
  188. class Condition:
  189.     """Synchronized condition variable object.
  190.  
  191.     *** DO NOT SUBCLASS THIS CLASS ***
  192.  
  193.     A condition variable is always associated with some kind of lock;
  194.     this can be passed in or one will be created by default.  (Passing
  195.     one in is useful when several condition variables must share the
  196.     same lock.)
  197.  
  198.     A condition variable has acquire() and release() methods that call
  199.     the corresponding methods of the associated lock.
  200.  
  201.     It also has a wait() method, and notify() and notifyAll() methods.
  202.     These three must only be called when the calling thread has
  203.     acquired the lock.
  204.  
  205.     The wait() method releases the lock, and then blocks until it is
  206.     awakened by a notifiy() or notifyAll() call for the same condition
  207.     variable in another thread.  Once awakened, it re-acquires the
  208.     lock and returns.  It is also possible to specify a timeout.
  209.  
  210.     The notify() method wakes up one of the threads waiting for the
  211.     condition variable, if any are waiting.  The notifyAll() method
  212.     wakes up all threads waiting for the condition variable.
  213.  
  214.     Note: the notify() and notifyAll() methods don't release the
  215.     lock; this means that the thread or threads awakened will not
  216.     return from their wait() call immediately, but only when the
  217.     thread that called notify() or notifyAll() finally relinquishes
  218.     ownership of the lock.
  219.  
  220.     Tip: the typical programming style using condition variables uses
  221.     the lock to synchronize access to some shared state; threads that
  222.     are interested in a particular change of state call wait()
  223.     repeatedly until they see the desired state, while threads that
  224.     modify the state call notify() or notifyAll() when they change the
  225.     state in such a way that it could possibly be a desired state for
  226.     one of the waiters.  For example, the following code is a generic
  227.     producer-consumer situation with unlimited buffer capacity:
  228.  
  229.         # Consume one item
  230.         cv.acquire()
  231.         while not an_item_is_available():
  232.             cv.wait()
  233.         get_an_available_item()
  234.         cv.release()
  235.  
  236.         # Produce one item
  237.         cv.acquire()
  238.         make_an_item_available()
  239.         cv.notify()
  240.         cv.release()
  241.  
  242.     To choose between notify() and notifyAll(), consider whether one
  243.     state change can be interesting for only one or several waiting
  244.     threads.  E.g. in a typical producer-consumer situation, adding
  245.     one item to the buffer only needs to wake up one consumer thread.
  246.  
  247.     """
  248.  
  249.     def __init__(self, lock=None):
  250.         """Constructor.
  251.  
  252.         If the lock argument is given and not None, it must be a Lock
  253.         or RLock object, and it is used as the underlying lock.
  254.         Otherwise, a new RLock object is created and used as the
  255.         underlying lock.
  256.  
  257.         """
  258.  
  259.     def acquire(self, *args):
  260.         """Acquire the underlying lock.
  261.  
  262.         This method calls the corresponding method on the underlying
  263.         lock; the return value is whatever that method returns.
  264.  
  265.         """
  266.  
  267.     def release(self):
  268.         """Release the underlying lock.
  269.  
  270.         This method calls the corresponding method on the underlying
  271.         lock; there is no return value.
  272.  
  273.         """
  274.  
  275.     def wait(self, timeout=None):
  276.         """Wait until notified or until a timeout occurs.
  277.  
  278.         This must only be called when the calling thread has acquired
  279.         the lock.
  280.  
  281.         This method releases the underlying lock, and then blocks
  282.         until it is awakened by a notify() or notifyAll() call for the
  283.         same condition variable in another thread, or until the
  284.         optional timeout occurs.  Once awakened or timed out, it
  285.         re-acquires the lock and returns.
  286.  
  287.         When the timeout argument is present and not None, it should
  288.         be a floating point number specifying a timeout for the
  289.         operation in seconds (or fractions thereof).
  290.  
  291.         When the underlying lock is an RLock, it is not released using
  292.         its release() method, since this may not actually unlock the
  293.         lock when it was acquired() multiple times recursively.
  294.         Instead, an internal interface of the RLock class is used,
  295.         which really unlocks it even when it has been recursively
  296.         acquired several times.  Another internal interface is then
  297.         used to restore the recursion level when the lock is
  298.         reacquired.
  299.  
  300.         """
  301.  
  302.     def notify(self):
  303.         """Wake up a thread waiting on this condition, if any.
  304.  
  305.         This must only be called when the calling thread has acquired
  306.         the lock.
  307.  
  308.         This method wakes up one of the threads waiting for the
  309.         condition variable, if any are waiting; it is a no-op if no
  310.         threads are waiting.
  311.  
  312.         The current implementation wakes up exactly one thread, if any
  313.         are waiting.  However, it's not safe to rely on this behavior.
  314.         A future, optimized implementation may occasionally wake up
  315.         more than one thread.
  316.  
  317.         Note: the awakened thread does not actually return from its
  318.         wait() call until it can reacquire the lock.  Since notify()
  319.         does not release the lock, its caller should.
  320.  
  321.         """
  322.  
  323.     def notifyAll(self):
  324.         """Wake up all threads waiting on this condition.
  325.  
  326.         This method acts like notify(), but wakes up all waiting
  327.         threads instead of one.
  328.  
  329.         """
  330.  
  331.  
  332. class Semaphore:
  333.     """Semaphore object.
  334.  
  335.     This is one of the oldest synchronization primitives in the
  336.     history of computer science, invented by the early Dutch computer
  337.     scientist Edsger W. Dijkstra (he used P() and V() instead of
  338.     acquire() and release()).
  339.  
  340.     A semaphore manages an internal counter which is decremented by
  341.     each acquire() call and incremented by each release() call.  The
  342.     counter can never go below zero; when acquire() finds that it is
  343.     zero, it blocks, waiting until some other thread calls release().
  344.  
  345.     """
  346.  
  347.     def __init__(self, value=1):
  348.         """Constructor.
  349.  
  350.         The optional argument gives the initial value for the internal
  351.         counter; it defaults to 1.
  352.  
  353.         """
  354.  
  355.     def acquire(self, blocking=1):
  356.         """Acquire a semaphore.
  357.  
  358.         When invoked without arguments: if the internal counter is
  359.         larger than zero on entry, decrement it by one and return
  360.         immediately.  If it is zero on entry, block, waiting until
  361.         some other thread has called release() to make it larger than
  362.         zero.  This is done with proper interlocking so that if
  363.         multiple acquire() calls are blocked, release() will wake
  364.         exactly one of them up.  The implementation may pick one at
  365.         random, so the order in which blocked threads are awakened
  366.         should not be relied on.  There is no return value in this
  367.         case.
  368.  
  369.         When invoked with the 'blocking' argument set to true, do the
  370.         same thing as when called without arguments, and return true.
  371.  
  372.         When invoked with the 'blocking' argument set to false, do not
  373.         block.  If a call without argument would block, return false
  374.         immediately; otherwise, do the same thing as when called
  375.         without arguments, and return true.
  376.  
  377.         """
  378.  
  379.     def release(self):
  380.         """Release a semaphore.
  381.  
  382.         Increment the internal counter by one.  When it was zero on
  383.         entry and another thread is waiting for it to become larger
  384.         than zero again, wake up that thread.
  385.  
  386.         """
  387.  
  388.  
  389. class Event:
  390.     """Event object.
  391.  
  392.     This is one of the simplest mechanisms for communication between
  393.     threads: one thread signals an event and another thread, or
  394.     threads, wait for it.
  395.  
  396.     An event object manages an internal flag that can be set to true
  397.     with the set() method and reset to false with the clear() method.
  398.     The wait() method blocks until the flag is true.
  399.  
  400.     """
  401.  
  402.     def __init__(self):
  403.         """Constructor.
  404.  
  405.         The internal flag is initially false.
  406.  
  407.         """
  408.  
  409.     def isSet(self):
  410.         """Return true iff the internal flag is true."""
  411.  
  412.     def set(self):
  413.         """Set the internal flag to true.
  414.  
  415.         All threads waiting for it to become true are awakened.
  416.  
  417.         Threads that call wait() once the flag is true will not block
  418.         at all.
  419.  
  420.         """
  421.  
  422.     def clear(self):
  423.         """Reset the internal flag to false.
  424.  
  425.         Subsequently, threads calling wait() will block until set() is
  426.         called to set the internal flag to true again.
  427.  
  428.         """
  429.  
  430.     def wait(self, timeout=None):
  431.         """Block until the internal flag is true.
  432.  
  433.         If the internal flag is true on entry, return immediately.
  434.         Otherwise, block until another thread calls set() to set the
  435.         flag to true, or until the optional timeout occurs.
  436.  
  437.         When the timeout argument is present and not None, it should
  438.         be a floating point number specifying a timeout for the
  439.         operation in seconds (or fractions thereof).
  440.  
  441.         """
  442.  
  443.  
  444. class Thread:
  445.     """Thread class.
  446.  
  447.     *** ONLY OVERRIDE THE __init__() AND run() METHODS OF THIS CLASS ***
  448.  
  449.     This class represents an activity that is run in a separate thread
  450.     of control.  There are two ways to specify the activity: by
  451.     passing a callable object to the constructor, or by overriding the
  452.     run() method in a subclass.  No other methods (except for the
  453.     constructor) should be overridden in a subclass.
  454.  
  455.     Once a thread object is created, its activity must be started by
  456.     calling the thread's start() method.  This invokes the run()
  457.     method in a separate thread of control.
  458.  
  459.     Once the thread's activity is started, the thread is considered
  460.     'alive' and 'active' (these concepts are almost, but not quite
  461.     exactly, the same; their definition is intentionally somewhat
  462.     vague).  It stops being alive and active when its run() method
  463.     terminates -- either normally, or by raising an unhandled
  464.     exception.  The isAlive() method tests whether the thread is
  465.     alive.
  466.  
  467.     Other threads can call a thread's join() method.  This blocks the
  468.     calling thread until the thread whose join() method is called
  469.     is terminated.
  470.  
  471.     A thread has a name.  The name can be passed to the constructor,
  472.     set with the setName() method, and retrieved with the getName()
  473.     method.
  474.  
  475.     A thread can be flagged as a ``daemon thread''.  The significance
  476.     of this flag is that the entire Python program exits when only
  477.     daemon threads are left.  The initial value is inherited from the
  478.     creating thread.  The flag can be set with the setDaemon() method
  479.     and retrieved with the getDaemon() method.
  480.  
  481.     There is a ``main thread'' object; this corresponds to the
  482.     initial thread of control in the Python program.  It is not a
  483.     daemon thread.
  484.  
  485.     There is the possibility that ``dummy thread objects'' are
  486.     created.  These are thread objects corresponding to ``alien
  487.     threads''.  These are threads of control started outside the
  488.     threading module, e.g. directly from C code.  Dummy thread objects
  489.     have limited functionality; they are always considered alive,
  490.     active, and daemonic, and cannot be join()ed.  They are never
  491.     deleted, since it is impossible to detect the termination of alien
  492.     threads.
  493.  
  494.     """
  495.  
  496.     def __init__(self, group=None, target=None, name=None,
  497.                  args=(), kwargs={}):
  498.         """Thread constructor.
  499.  
  500.         This constructor should always be called with keyword
  501.         arguments.  Arguments are:
  502.  
  503.         group
  504.             Should be None; reserved for future extension when a
  505.             ThreadGroup class is implemented.
  506.  
  507.         target
  508.             Callable object to be invoked by the run() method.
  509.             Defaults to None, meaning nothing is called.
  510.  
  511.         name
  512.             The thread name.  By default, a unique name is constructed
  513.             of the form ``Thread-N'' where N is a small decimal
  514.             number.
  515.  
  516.         args
  517.             Argument tuple for the target invocation.  Defaults to ().
  518.  
  519.         kwargs
  520.             Keyword argument dictionary for the target invocation.
  521.             Defaults to {}.
  522.  
  523.         If the subclass overrides the constructor, it must make sure
  524.         to invoke the base class constructor (Thread.__init__())
  525.         before doing anything else to the thread.
  526.  
  527.         """
  528.  
  529.     def start(self):
  530.         """Start the thread's activity.
  531.  
  532.         This must be called at most once per thread object.  It
  533.         arranges for the object's run() method to be invoked in a
  534.         separate thread of control.
  535.  
  536.         """
  537.  
  538.     def run(self):
  539.         """Method representing the thread's activity.
  540.  
  541.         You may override this method in a subclass.  The standard
  542.         run() method invokes the callable object passed as the
  543.         'target' argument, if any, with sequential and keyword
  544.         arguments taken from the 'args' and 'kwargs' arguments,
  545.         respectively.
  546.  
  547.         """
  548.  
  549.     def join(self, timeout=None):
  550.         """Wait until the thread terminates.
  551.  
  552.         This blocks the calling thread until the thread whose join()
  553.         method is called terminates -- either normally or through an
  554.         unhandled exception -- or until the optional timeout occurs.
  555.  
  556.         When the timeout argument is present and not None, it should
  557.         be a floating point number specifying a timeout for the
  558.         operation in seconds (or fractions thereof).
  559.  
  560.         A thread can be join()ed many times.
  561.  
  562.         A thread cannot join itself because this would cause a
  563.         deadlock.
  564.  
  565.         It is an error to attempt to join() a thread before it has
  566.         been started.
  567.  
  568.         """
  569.  
  570.     def getName(self):
  571.         """Return the thread's name."""
  572.  
  573.     def setName(self, name):
  574.         """Set the thread's name.
  575.  
  576.         The name is a string used for identification purposes only.
  577.         It has no semantics.  Multiple threads may be given the same
  578.         name.  The initial name is set by the constructor.
  579.  
  580.         """
  581.  
  582.     def isAlive(self):
  583.         """Return whether the thread is alive.
  584.  
  585.         Roughly, a thread is alive from the moment the start() method
  586.         returns until its run() method terminates.
  587.  
  588.         """
  589.  
  590.     def isDaemon(self):
  591.         """Return the thread's daemon flag."""
  592.  
  593.     def setDaemon(self, daemonic):
  594.         """Set the thread's daemon flag (a Boolean).
  595.  
  596.         This must be called before start() is called.
  597.  
  598.         The initial value is inherited from the creating thread.
  599.  
  600.         The entire Python program exits when no active non-daemon
  601.         threads are left.
  602.  
  603.         """
  604.  
  605.  
  606. # Module-level functions:
  607.  
  608.  
  609. def currentThread():
  610.     """Return the current Thread object.
  611.  
  612.     This function returns the Thread object corresponding to the
  613.     caller's thread of control.
  614.  
  615.     If the caller's thread of control was not created through the
  616.     threading module, a dummy thread object with limited functionality
  617.     is returned.
  618.  
  619.     """
  620.  
  621.  
  622. def activeCount():
  623.     """Return the number of currently active Thread objects.
  624.  
  625.     The returned count is equal to the length of the list returned by
  626.     enumerate().
  627.  
  628.     """
  629.  
  630.  
  631. def enumerate():
  632.     """Return a list of all currently active Thread objects.
  633.  
  634.     The list includes daemonic threads, dummy thread objects created
  635.     by currentThread(), and the main thread.  It excludes terminated
  636.     threads and threads that have not yet been started.
  637.  
  638.     """
  639.